CSV FIELD DOCUMENTATION
=======================

areas.csv
---------
Primary node label: Area

Fields:
- id: Unique area identifier. Example: A001.
- name: Commercial area name. Example: Attica.

Meaning:
Area is the top-level commercial geography. It groups multiple territories.


territories.csv
---------------
Primary node label: Territory

Fields:
- id: Unique territory identifier. Example: T001.
- name: Territory name.
- areaId: Parent Area id.
- urbanType: Territory character, for example urban, suburban, rural or mixed.
- populationBand: Relative population/market size band, for example low, medium or high.

Meaning:
Territory is the IQVIA (global healthcare analytics company) geography level where external market sales are available.
Pharmacies belong to territories.
Market sales are reported at territory level, not pharmacy level.


pharmacies.csv
--------------
Primary node label: Pharmacy

Fields:
- id: Unique pharmacy identifier. Example: PH00001.
- name: Pharmacy display name.
- territoryId: Territory where the pharmacy is located.
- tier: Commercial pharmacy tier.
  - A = top 20% pharmacies.
  - B = middle 40% pharmacies.
  - C = bottom 40% pharmacies.
- sizeIndex: Relative size of the pharmacy. This is a structural size indicator, not a loyalty or growth score.
- urbanType: Local pharmacy environment, for example urban, suburban or rural.

Meaning:
Pharmacy is the only customer type in the dataset.
Pharmacy behavior metrics such as loyalty, growth potential and price sensitivity should be calculated from internal sales history, discount response and product basket behavior.


categories.csv
--------------
Primary node label: ProductCategory

Fields:
- id: Unique product category identifier. Example: CAT001.
- name: Category name. Example: Vitamins, Skincare, Sunscreens.

Meaning:
ProductCategory groups OTC products and is the level at which IQVIA-like market sales are reported.


products.csv
------------
Primary node label: Product

Fields:
- id: Unique product identifier. Example: P0001.
- name: Product/SKU name.
- brand: Product brand name.
- manufacturerId: Manufacturer that owns the product.
- categoryId: Product category.
- listPrice: Product list price before discount.
- marginPct: Product gross margin percentage.
- launchMonthIndex: Month index when the product was launched.

Meaning:
Products are commercial OTC SKUs sold by manufacturers.
Product lifecycle stage is not stored; it should be derived from launchMonthIndex and the selected analysis month.

Example derived lifecycle logic:
- analysisMonthIndex - launchMonthIndex <= 6: Launch
- 7 to 18: Growth
- 19 to 36: Mature
- over 36: Late/Mature or Decline candidate, depending on sales trend


manufacturers.csv
-----------------
Primary node label: Manufacturer

Fields:
- id: Unique manufacturer identifier. Example: M001.
- name: Manufacturer/company name.
- type: Manufacturer type.
  - OWN_COMPANY = the company owning the internal sales dataset.
  - COMPETITOR = competing manufacturer visible only through market scan data.

Meaning:
Manufacturer is used in both product ownership and IQVIA-like market sales.
Competitor strength and market pressure are derived from MarketSale facts, not stored as manufacturer attributes.


months.csv
----------
Primary node label: Month

Fields:
- id: Unique month id in YYYY-MM format.
- year: Calendar year.
- month: Calendar month number, 1 to 12.
- quarter: Calendar quarter, 1 to 4.
- index: Continuous month index used for time-series analysis.
- season: Season label, for example winter, spring, summer, autumn.

Meaning:
Month is modeled as a graph node to support temporal analytics, trend calculations and period comparisons.


sales_reps.csv
--------------
Primary node label: SalesRep

Fields:
- id: Unique sales rep identifier. Example: R001.
- name: Sales rep display name.
- experienceYears: Years of experience.

Meaning:
SalesRep represents the field force.
Effectiveness and discount discipline are not stored; they should be derived from internal sales, growth trends, profitability and discount behavior.


sales_rep_territories.csv
-------------------------
Relationship source: SalesRep
Relationship target: Territory
Relationship type: COVERS

Fields:
- salesRepId: Sales rep id.
- territoryId: Territory id covered by the rep.
- coverageRole: Role of coverage, for example primary or secondary.

Meaning:
This file maps sales reps to territories and supports territory coverage and sales force analytics.


promotion.csv / promotions.csv
------------------------------
Primary node label: Promotion

Fields:
- id: Unique promotion identifier.
- name: Promotion/campaign name.
- categoryId: Target product category.
- territoryId: Target territory.
- startMonthIndex: Start month index.
- endMonthIndex: End month index.
- mechanic: Promotion mechanic, for example TRAINING, VISIBILITY, BUNDLE or DISCOUNT.

Meaning:
Promotion represents commercial campaigns active for a category in a territory during a time window.
Promotion effectiveness should be derived from internal sales uplift, net profit uplift and post-promotion sustainability.


Note:
The actual file name in this dataset is promotions.csv.


discount_policies.csv
---------------------
Primary node label: DiscountPolicy

Fields:
- id: Unique discount policy identifier.
- name: Policy name.
- type: Policy type, for example STANDARD_TIER, SEASONAL, LAUNCH or VOLUME.
- minPct: Minimum allowed discount percentage.
- maxPct: Maximum allowed discount percentage.
- targetTier: Target pharmacy tier. Can be A, B, C or empty/all depending on policy.
- targetCategoryId: Target category id. Can be empty when the policy is not category-specific.
- startMonthIndex: Policy start month index.
- endMonthIndex: Policy end month index.

Meaning:
DiscountPolicy defines commercial discount rules.
Actual discount used is stored on InternalSale as discountPct and discountValue.
Optimal discount, elasticity and margin impact should be calculated from InternalSale facts.


internal_sales.csv
------------------
Primary node label: InternalSale

Fields:
- id: Unique internal sale fact identifier.
- pharmacyId: Pharmacy that made the purchase.
- productId: Product sold.
- monthId: Month of sale.
- salesRepId: Sales rep associated with the sale.
- discountPolicyId: Discount policy used.
- promotionId: Promotion influencing the sale. Can be empty.
- units: Units sold.
- grossRevenue: Revenue before discount.
- discountPct: Actual discount percentage applied.
- discountValue: Monetary discount value.
- netRevenue: Revenue after discount.
- grossProfit: Profit before commercial deductions.
- netProfit: Final profit after discount impact.
- stockoutDays: Estimated number of days in the month when product was out of stock.

Meaning:
InternalSale is the company-owned transactional/monthly fact layer.
It supports pharmacy-level analysis, rep analysis, discount analysis, profitability and portfolio analytics.

Important:
This file is not market share data.
Market share should be calculated by comparing internal/own-company sales with market_sales.csv at compatible territory/category/month level.


market_sales.csv
----------------
Primary node label: MarketSale

Fields:
- id: Unique market sale fact identifier.
- territoryId: Territory where the market sales were observed.
- categoryId: Product category.
- manufacturerId: Manufacturer selling in the market.
- monthId: Month of market scan.
- units: Estimated total units sold by this manufacturer in this territory/category/month.
- valueSales: Estimated total value sales by this manufacturer in this territory/category/month.

Meaning:
MarketSale is the IQVIA-like external market scan layer.
It does not contain pharmacy-level data.
It is used for market share, competitor share, category growth and share erosion analytics.

Example derived metrics:
- own company market share
- competitor market share
- total category market size
- category growth
- manufacturer share movement
- competitive pressure

